home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / util / time / PictureClock.lha / PictureClock / PictureClock.doc < prev    next >
Text File  |  1994-08-22  |  24KB  |  491 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                            PictureClock V39.72
  7.                                 release 1.1
  8.  
  9.                                 _________
  10.                              .      |      .
  11.                            .           /     .
  12.                           .           /       .
  13.                           |          /        |
  14.                           |-    ____/        -|
  15.                           |                   |
  16.                           .                   .
  17.                            .                 .
  18.                              .             .
  19.                                 ____|____
  20.  
  21.  
  22.                   A broadcast clock for Amiga computers
  23.     Works with Amiga OS V39 and up, also requires datatype.library V39
  24.      1 MB chip memory recommended for ECS graphics (up to 32 colours)
  25.      2 MB chip memory recommended for AA graphics (up to 256 colours)
  26.  
  27.                  © Copyright 1994 by Maarten C. ter Mors
  28.                            All rights reserved.
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42. Legal issues                                                        page 1
  43. --------------------------------------------------------------------------
  44.  
  45. Okay,  let's  get  this  out  of  the way first :  the things you may and,
  46. mostly, the things you must and may _not_ do.
  47.  
  48. This  program, PictureClock, and its source code are copyrighted material.
  49. That  means  you  may  not  make  a  profit out of it or out of part of it
  50. without  the  author's  written permission.  You are, however, allowed and
  51. even  encouraged  to  distribute this program in any way you can, provided
  52. that  you  a)  keep  the  distribution  complete  and distribute it in its
  53. original form and b) do not charge anybody money for it.  If you intend to
  54. sell  it  or  use  it  for  any  other  commercial  purpose  that involves
  55. exchanging  PictureClock  for  any  other object of value, you must always
  56. first contact the author (see page 9).
  57.  
  58. The  inclusion  of  PictureClock in a public domain library is encouraged,
  59. just  so  long  as  no  more  than  the equivalent of US$ 5 is charged for
  60. copying  the  disk,  the  disk  itself  and the shipping/handling.  If you
  61. intend  to  include  this program on a CD-ROM and the author did _not_ ask
  62. you to do so, he would be grateful for a copy of the CD-ROM in question.
  63.  
  64. PictureClock  was  intended as a tool for people who work with television,
  65. video  or multimedia presentations.  Therefor you may use the clock freely
  66. on  television,  video  tapes  or  during  presentations,  on screens in a
  67. conference  hall, and so on.  This goes for all sorts of productions, from
  68. filling  the fifteen-second gap to the seven o' clock news, through motion
  69. pictures,  to  counting down the last seconds before midnight on Newyear's
  70. Eve.
  71. What  you  may  NOT do is offer PictureClock as a service that you will be
  72. paid  for,  i.e.  if you run a video production company and receive a call
  73. from  a  TV station, for example.  You must then contact the author and he
  74. will try to work something out with you.
  75.  
  76. As for the source code, it is mostly intended to learn from, as I have
  77. learned from other people's source code in the past.  It is allowed to use
  78. parts of it in your own programs, as long as you : a) contact the author
  79. beforehand, so that he will be notified in advance and b) mention the
  80. author's name and the copyrights to his code along with your own copyright
  81. messages in the documentation to your program.
  82.  
  83. See also : Notes on using the source code, page 6
  84.            About the author, page 9
  85.  
  86.  
  87. Introduction                                                        page 2
  88. --------------------------------------------------------------------------
  89.  
  90. We've  all  seen  'em,  the  clocks on TV that fill your entire screen and
  91. slowly  tick  away  the  seconds  that  separate you from the start of yet
  92. another  episode of Dallas.  Some of you may have thought they were great,
  93. fab examples of video artwork, others may have tapped their fingers on the
  94. table,  desperately  wanting  them  to  go  away.   Some  nutcase computer
  95. programmers  may  even have thought :  'I could do better than that.' Yep,
  96. you guessed it, I was one of those.
  97. I started programming this clock for no particular reason, other than that
  98. my  summer  holidays  were  well  underway, which gave me a lot of time to
  99. spare, and that I wanted to experiment a bit with the new OS 3 datatypes a
  100. bit.   So,  PictureClock  effectively  was  born as a small program called
  101. 'datatypetest.c',  which  was  no  more  than a datatype-dependent picture
  102. viewer, and not a very good one at that.
  103. However,  then  I started to incorporate some older ideas that I had lying
  104. around  in this head of mine.  Coincedentally, I had recently been helping
  105. someone programming a small titlebar clock utility, so the idea of a clock
  106. came  to  mind.   I  had  always  wanted to do something with sound on the
  107. Amiga,  so  I  added  a  subtask that chimes joyfully every whole and half
  108. hour,  also  through  the  (fabulous, albeit slow) datatype interface.  In
  109. all,  I renamed datatypetest.c to PictureClock.c and things really started
  110. to roll along.
  111.  
  112. Well,  what  is it then ?  After having let you read all the crap above, I
  113. think  I'm  obliged to tell you now.  PictureClock is a full-screen analog
  114. clock  utility, that draws a clock on top of a bitmap picture, that can be
  115. in any format, just as long as you have a pictureclass datatype to support
  116. it.
  117. Currently  I  know of picture ones for ILBM, GIF, JPEG, BMP, MacPaint, Sun
  118. Rasterfiles, Paintbrush (PCX) and I am still looking for one for PhotoCD -
  119. if  anyone knows of a PhotoCD.datatype, please let me know !  Else I might
  120. consider writing one myself.
  121. PictureClock  will  automatically  adapt  to  your  overscan  size, center
  122. pictures  any  size  on-screen  (if they are too large for the display, it
  123. will  take whatever it can of the top lefthand corner).  Theoretically, it
  124. will adapt itself to any size you care to throw at it, although very small
  125. pictures are not very useful ; the whole point of the program, is a clear,
  126. easy-to-read  clock  that you can see from a long way away if you have to.
  127. And on a 64x64 brush it will just be too tiny for that.
  128. You  can tell PictureClock which picture to use by means of a command line
  129. from  the  Shell,  by  using  a  Project icon with its default tool set to
  130. PictureClock   from   Workbench,   by   a   ToolType  option  or  even  by
  131. shift-clicking.   In all cases, you can supply the name of a picture file,
  132. or  the  name  of  a directory with pictures in it from which PictureClock
  133. chooses a picture at random.
  134. Also,  you  can  use  any  datatype-supported  sound sample (datatypes are
  135. availible for 8SVX, WAV and other formats) to use as a 'chime' sound, just
  136. like  an  ancient  church  bell.   PictureClock  even  supports a delay in
  137. seconds between alternate chimes, because else large samples could overlap
  138. and that sounds silly.  Besides, a solemn graveyard bell loses much of its
  139. eerie sound when it's rung too quickly.
  140.  
  141.  
  142. How to use PictureClock                                             page 3
  143. --------------------------------------------------------------------------
  144.  
  145. PictureClock  takes  a number of options.  From the CLI, you type these on
  146. the command line, after the name of the program.  Like :
  147.  
  148.     PictureClock DH2:Pictures/Background.IFF NOTICK CONTINUOUS
  149.  
  150. If you start the program from Workbench, you can enter the options through
  151. the  so-called ToolTypes.  These appear when you click on the program icon
  152. once  and  select 'Information' from the Icon menu.  Here are the options,
  153. then, in all their glory :
  154.  
  155. PICTURE
  156. =======
  157.  
  158. Behind  this  you  type  the name of the picture file you want to use as a
  159. background  for  your clock.  It is also possible to specify the name of a
  160. directory,  in  which PictureClock will search for picture files.  Do make
  161. sure  that  the  file(s)  is/are  not  in  HAM  format,  since this is not
  162. supported by PictureClock (on page 5 I'll tell you why not).
  163.  
  164. SOUND
  165. =====
  166.  
  167. Behind  this  belongs  the  name  of  the  sound  sample  to  use  for the
  168. semi-hourly  'chime' sound.  Just as with PICTURE above, the format of the
  169. file has to be supported by the datatypes installed on your system.
  170. I have included one sound sample in the archive, Bell, which is the solemn
  171. church bell I mentioned earlier.  Anybody have a cuckoo sample for me ?
  172.  
  173. WAITBETWEENSAMPLES (=WAIT)
  174. ==========================
  175.  
  176. This  option  takes a number value that indicates the number of seconds to
  177. wait  between  chimes.   This only applies to the full hour of course.  To
  178. make  the  Bell  sound  sound  good,  a  WAITBETWEENSAMPLES  value of 1 is
  179. recommended.
  180.  
  181. NOSEC
  182. =====
  183.  
  184. This turns the (red) seconds arm of the clock off.
  185.  
  186. NOTICK
  187. ======
  188.  
  189. By  default,  PictureClock  generates  an  InputEvent  every  second, that
  190. pretends to tap the left shift key.  I have done this for two reasons :
  191.  
  192. 1)  to  keep  the screenblanker away and prevent it from blanking out your
  193. clock  in  the  middle  of  a  live  TV  performance  (doesn't  look  very
  194. professional and the owner of the TV station might not be overly pleased).
  195. 2)  in  conjunction with the commodity Yak, which was written by Martin W.
  196. Scott  & Gaël Marziou, and its keyclick feature, this makes a nice ticking
  197. sound every second.  Just like a clock, really.
  198.  
  199.  
  200. How to use PictureClock                                             page 4
  201. --------------------------------------------------------------------------
  202.  
  203. CONTINUOUS (=CONT)
  204. ==================
  205.  
  206. By  default, the minute arm of the clock jumps forward one minute when the
  207. seconds  reach  0.   Now of course I know this is not the way a real clock
  208. works  (not  an  analog  one,  anyway),  and  so  you  can tell it to move
  209. continually around the clock dial.  If you look very closely you can still
  210. see  it  nudge  itself  forward  a  bit each second, especially on a LoRes
  211. screen, where the pixels are larger.  However, my antique clock downstairs
  212. (which  is  really  _fully_  analog)  does  this  too  on close inspection
  213. (especially when I put it in LoRes mode :-).
  214. I  personally don't like the CONTINUOUS option (if only for the spelling),
  215. because  the  minute  arm literally seems to crawl along, as if it's never
  216. learned  to  stand  still !  But then, you may love it and so I decided to
  217. leave the option in.  Go ahead, say it, I'm a nice guy :-))
  218.  
  219. BESTMODEID
  220. ==========
  221.  
  222. This  option  lets  PictureClock  override  the  ModeID  supplied  by  the
  223. datatype, because some have a way of providing rather dodgy ModeIDs, which
  224. render  your  picture rather strangely.  It will call the graphics.library
  225. function  BestModeID()  to  sort  out  the  optimal  screen  mode for your
  226. picture.
  227. Use this option if you think your pictures don't look the way you remember
  228. them  (wrong  resolution,  wrong  overscan, etc.).  BESTMODEID can have an
  229. unwanted  side-effect, though :  it chooses the screen mode in such a way,
  230. that  it will suit the dimensions of the screen most properly.  That means
  231. that  if  you have a small picture of, say, 300 by 200 pixels or so, which
  232. was  actually  drawn in high resolution, it will appear on screen slightly
  233. streched.   This  is because BestModeID() will pick a Lores non-interlaced
  234. screen mode to fit the picture.
  235.  
  236. SLIM
  237. ====
  238.  
  239. It  has  come  to  my  attention, that some people thought the arms of the
  240. clock  were  too large.  Therefor, I added the SLIM option, which provides
  241. the  same  arms,  except  that  they suddenly seem to have lost half their
  242. weight :-) Now if only I could bottle this stuff...:-))
  243.  
  244.  
  245. What's still wrong with it                                          page 5
  246. --------------------------------------------------------------------------
  247.  
  248. PictureClock  has  its  flaws.   Apart from the fact that it could do with
  249. some  additional features (see page 7), there are some known problems with
  250. the program.  I will start with the most trivial :
  251.  
  252. -  The  abbreviation  sucks.   You  (probably)  don't  want to say to your
  253. friend :  'Hey Mick, I just got me this great program called PictureClock,
  254. it's  fab !  PictureClock can put a clock on my screen and I almost wet my
  255. pants  in delight when PictureClock started to chime the bells.  It's also
  256. got a doc with it, called PictureClock.doc and it's almost just as good as
  257. PictureClock itself !'
  258. Now even if you would want to blurt out a load of rubbish like that, you'd
  259. shorten  that  word  'PictureClock' every time to something like PC.  And,
  260. while  it  really  only  means  'Personal  Computer',  we all know what is
  261. generally  *really*  meant  when  somebody  says  'PC'.  He or she is then
  262. referring  to  those  large,  square boxes with noisy ventilators in them,
  263. that  require  a  SoundBlaster  and SVGA card to run a simple program like
  264. PC..er..PictureClock.
  265.  
  266. -  The  program icon isn't much better.  Apart from the fact that it looks
  267. terrible,  I  might  get  sued by Electronic Arts for unauthorised use and
  268. abuse of their DeluxePaint picture icon.  Any unemployed artists out there
  269. to make me a proper icon ?
  270.  
  271. - PictureClock does not support HAM pictures.  Believe me, I've tried, but
  272. it's  really  no  use.   Getting  the picture on screen is no problem, but
  273. drawing  a  clock  over the top of it is hopeless.  All the fringing makes
  274. the  picture  look  like my mother-in-law on a very bad day indeed and the
  275. calculations  to fix it every second eat up far too much processor time to
  276. do anything else.
  277.  
  278. -  PictureClock hangs.  It doesn't crash, but it just hangs there when you
  279. change the system time to an earlier value than before, while PictureClock
  280. is  running.   I  know  why  it  happens  - the TimeRequest the program is
  281. waiting  for is not replied to until the original time comes around and so
  282. it  waits  in  vain for a long time.  This is probably the reason why Phil
  283. Collins sang, in one of the songs of his Both Sides album :
  284.  
  285.     Sometimes, hits me in the morning, hits me at night,
  286.     that I cannot turn back the years
  287.  
  288. Notes on using the source code                                      page 6
  289. --------------------------------------------------------------------------
  290.  
  291. The file PictureClock.c, which should be in this archive (if not, you have
  292. been  given  an  incomplete  archive  -  contact me for a complete one !),
  293. contains the C source code to PictureClock.  Now you too can see how I did
  294. it,  marvel  at  the clever bits of, drool over the beautiful parts of but
  295. most of all laugh at the inevitable, stupid mistakes in my code.
  296. You  will  notice  that the source is a bit of a mess ; for one thing, all
  297. the  code resides in one module and the better part of that is taken up by
  298. only  one  routine, the quite huge main() part.  There are two reasons for
  299. this,  one  is  that  I started to write PictureClock as a try-out for the
  300. datatype  routines  and more and more grew on as time went by.  The second
  301. reason is, that most of PictureClock's operation is pretty linear anyway :
  302. first  parse  the  arguments,  open  the  resources, the picture file, the
  303. screen, the window, draw the clock layout and so on.  Then, all the way at
  304. the  end of main(), there is a very small loop that is the actual heart of
  305. the program ; this is where the clock is actually being run from.
  306.  
  307. I'm sorry that the source is also poorly commented, although I assume many
  308. things will be quite obvious.  I never do too many obscure things, and the
  309. one or two that are there are either commented on the spot after all, or
  310. else explained in the autodocs.  I recommend that you get them - they're
  311. an invaluable source of information for a serious programmer.  In fact, I
  312. don't think I could have written PictureClock (with all its V39 functions
  313. I'd never even seen before) without them.
  314.  
  315. The  reason  I  included  the  source  code,  is  that  you can make small
  316. adaptations  to  the  code  yourself  (provided  of  course that you are a
  317. programmer)  if something does not suit you or if you have found a bug you
  318. know how to fix.  I'd like to know about the bugs.
  319. You  are  allowed  to  do  so  for your own use.  What I'd rather have you
  320. didn't  (in  other  words  :   DON'T !), is distributing the adapted/fixed
  321. version  yourself.   This  could  cause  too  large  a number of different
  322. versions  of  PictureClock made public, which in turn causes confusion and
  323. frustration.   Two users who both use PictureClock 1.1 should get the same
  324. program,  not  two  different  ones  with the same version number stuck to
  325. them.
  326. If  you  have  made  a  change  that  you  think  could be useful to other
  327. PictureClock users, send it to me and I'll make it availible with the next
  328. release.   I will release a new version when either many changes have been
  329. made,  or there is one particular change that is so urgent (a serious bug,
  330. for example) that a new version needs to be brought out straight away.
  331.  
  332.  
  333. Program history                                                     page 7
  334. --------------------------------------------------------------------------
  335.  
  336. I  started programming at V39.00.  That was a really useless program, with
  337. more errors than features and larger debug- than code hunks.
  338.  
  339. Seventy-two  revisions, additions and bugfixes later, I think PictureClock
  340. is  ready  to face the music.  It is still far from perfect, and offhand I
  341. can think of a dozen features I could add to make the program all the more
  342. pretty and useful.  Here are some I could do :
  343.  
  344. -  ARexx  support.   Especially  in  a  TV/video  environment, it could be
  345. extermely  useful  if  you  could  let the clock tick until a certain time
  346. point, and then turn it off from ScalaMM for example.
  347.  
  348. -  Alarm  timer.   Do something (ARexx script ?) when a certain time point
  349. has  been  reached.   In the above example, PictureClock could turn itself
  350. off when the time has come to do so.
  351.  
  352. NOTE  :   It  _is_  possible  to  interrupt  PictureClock from an external
  353. program,  for  example  an  ARexx  script.   If you send it a CTRL-C break
  354. during  execution,  it will abort immediately.  And since there are plenty
  355. of programs for the Amiga, that will let you execute at an exact time, you
  356. could circumvent above problems with a little bit of clever experimenting.
  357.  
  358. - Screenblanker module.  PictureClock is ideally suited to be a module for
  359. (for  example) SuperDark, popping up after a period of inactivity from the
  360. user.   There  are only two problems with this :  1) the bars on the clock
  361. that  indicate  12,  3, 6 and 9 o' clock will still burn in on your screen
  362. and 2) so will the picture.  Problem 2 could be solved by adding :
  363.  
  364. -  Picture  alternation.   PictureClock  could  be told to change pictures
  365. every  now  and  then,  from  a directory with picture files.  This would,
  366. however,  require a lot of chip memory.  And PictureClock already takes up
  367. quite  a lot of that because of its double buffering, so that may become a
  368. problem.
  369.  
  370. -  Text  support.  Scroll a line of text in a user-defined font across the
  371. bottom  of  the  screen,  and then preferably at a certain time or through
  372. external  input  (see  above).   For  example  :   'Next on BBC 2 :  Monty
  373. Python's Flying Circus at 21:00'.
  374.  
  375. -  Weird  features.   Little  men  rubbing dirt off the arms of the clock,
  376. birds flying over the screen, a hollow laugh and some thunder at midnight,
  377. an irritating voice that tells you it's time to get up in the morning, and
  378. so on, and so on...
  379.  
  380. If enough people write to me that they're interested in a certain feature,
  381. then  I'll  get  it  there.  However, the source is included, so if you're
  382. worth your programming salt, make small changes yourself !  :-)
  383.  
  384.  
  385. Revision list                                                       page 8
  386. --------------------------------------------------------------------------
  387.  
  388. PictureClock V39.58 (distributed as release 1.0b)
  389. =================================================
  390.  
  391. First  release version.  Includes source - and documentation with too many
  392. terrible jokes in it.
  393.  
  394.  
  395. PictureClock V39.72 (distributed as release 1.1)
  396. ================================================
  397.  
  398. * BUG fix :    Apparently, the mouse pointer wasn't blanked in an entirely
  399. legal  way, which could cause rubbish on the screen when moving the mouse.
  400. This  has  now  been  fixed by using the recommended, official and far too
  401. complicated method for V39.
  402.  
  403. * BUG fix :      Sometimes,  the PictureClock sound sub-process would hang
  404. because of a problem with the stack.  Fixed.
  405.  
  406. *  Improvement  :   Cleaned  up  the  rather  awkward  manner in which the
  407. Workbench  ToolTypes  were  organised.   You  no  longer  have  to specify
  408. nonsense  like  'NOTICK=TRUE',  you  can now just type 'NOTICK', just like
  409. from  the CLI.  Consequently, there is no longer any need for the TICK and
  410. SEC options and they are no longer supported.
  411.  
  412. * Improvement :  Fixed some problems with the aspect ratio of the clock on
  413. strangely-sized pictures.  I used to calculate the pixel aspect ratio from
  414. the  dimensions  of the screen, now I go for the dimensions of the picture
  415. instead  (usually, there isn't much difference, unless the picture is much
  416. smaller than the screen).
  417.  
  418. * Improvement :  The size of the four clock bars is now fully dependent on
  419. the size of the picture.
  420.  
  421. * NEW feature :  Added the SLIM option for slimmer clock arms.
  422.  
  423. * NEW feature :  Added the BESTMODEID  option to  fix  problems with dodgy
  424. datatypes and wrong overscan settings.
  425.  
  426.  
  427. About the author                                                    page 9
  428. --------------------------------------------------------------------------
  429.  
  430. If  you  should  have  any  suggestions, bug reports, if you have made any
  431. changes to the source code of which you think it's worth it that they make
  432. it  into the next version of PictureClock, or if you just desperately want
  433. someone  to talk to (pretty women, this way please :-), then you can reach
  434. me at :
  435.  
  436.     Maarten ter Mors
  437.     Hendrik Vinkhof 47
  438.     2202 XJ Noordwijk
  439.     The Netherlands
  440.  
  441.     email : maarten.ter.mors@aobh.xs4all.nl
  442.     Fido  : 2:280/464.6
  443.  
  444. I'm  ready  for  fanmail,  hatemail, crazy mail, mail in yellow envelopes,
  445. mail  that  tastes  good  with pepper, mail in green envelopes, mailbombs,
  446. mail  in  any other colour envelope, no mail at all and even SERIOUS mail.
  447. I  do,  however,  prefer email whenever possible, it's so much easier (too
  448. bad about the coloured envelopes, though.  Damn !  :-)
  449. What  I'm  not  ready  for,  on  the other hand, is a great deal of money,
  450. Amigas  4000, shiny sportscars and houses by the sea.  So whatever you do,
  451. DON'T send them !
  452.  
  453. (Now let's see if it's true what they say, that people always do what you
  454. don't want them to :-)
  455.  
  456. Oh, and I don't expect the Spanish Inquisition either.
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463. 'NOBODY EXPECTS...'
  464.  
  465.  
  466.                                  THE END
  467.  
  468.  
  469. '....o bugger.'
  470.  
  471.  
  472. By the wee : my PeeGeePee key                                      page 10
  473. --------------------------------------------------------------------------
  474.  
  475. O  yeah,  by  the  way.   If you don't want your husbands to know, ladies,
  476. that's quite allright.  Here's my PGP public key for your convenience :
  477.  
  478. -----BEGIN PGP PUBLIC KEY BLOCK-----
  479. Version: 2.3a.2
  480.  
  481. mQCNAizFdygAAAEEAMUcoE5jO7xw13BVEdMwMuzc513YU55N0pOECQZvxpt+vJ0z
  482. WxDxuZ3bVgTR9YsP8ZkOZm4Eu8XCbqElenmnMMbBwKHScrF5SB/tpgHw/Xh8DHNm
  483. NgBvPnvNOW7x3DLZ27L+dvuuafJJ2RdA3NLLAoNAQX9sbS/ZNwLexz+VJ8G3AAUR
  484. tCFNYWFydGVuIEMuIHRlciBNb3JzIDwyOjI4MC80NjQuNj6JAJYCBRAsxq0kSnwH
  485. D6aK11kBAT4XBAIC0jZSswryiB6rcrb7Tj0DQGOvaZjFwQl6IJqIDsPUrLCH/tPY
  486. NnfzMCYcqe3ul72BW1hdPhE7YWjOaX2my0o54HH3J8R8y1CBcV521mTolcA+1/Rn
  487. drmiyt5eaRoXcE6rb0Nj4OEkHyluNLkvm6D8ZwTlVWIACdIanzTCCNhzMGG0EE1h
  488. YXJ0ZW4gdGVyIE1vcnM=
  489. =98JL
  490. -----END PGP PUBLIC KEY BLOCK-----
  491.